BCI NET/BCI NET Dec 94.iso/archives/programming/libraries/din.lha/Din/doc/Din.doc

Text File | 1994-11-23 | 16.9 KB | 772 lines

TABLE OF CONTENTS

din.library/NotifyDinLinks
din.library/ResetDinLinkFlags
din.library/MakeDinObject
din.library/EnableDinObject
din.library/DisableDinObject
din.library/PropagateDinObject
din.library/RemoveDinObject
din.library/LockDinObject
din.library/UnlockDinObject
din.library/FindDinObject
din.library/MakeDinLink
din.library/RemoveDinLink
din.library/ReadLockDinObject
din.library/ReadUnlockDinObject
din.library/WriteLockDinObject
din.library/WriteUnlockDinObject
din.library/LockDinBase
din.library/UnlockDinBase
din.library/InfoDinObject
din.library/FreeInfoDinObject


din.library/NotifyDinLinks            din.library/NotifyDinLinks

    NAME
    NotifyDinLinks -- Notify all links for a DinObject.

    SYNOPSIS
    Tasks = NotifyDinLinks(DinObject, Flags)
    D0             A0        D0

    ULONG Tasks;
    struct DinObject *DinObject;
    ULONG Flags;

    FUNCTION
    Sends a signal to all tasks linked to this DinObject.

    The only flag you can safely use is LNK_CHANGE. This function
    will fill in the Flags field for all the DinLinks linked to this
    DinObject and send a signal to the corresponding task.

    Use this function to tell everyone that you have changed something
    to your physical object.

    INPUTS
        DinObject = pointer to a DinObject (normally created by you).
        Flags = at this moment only LNK_CHANGE is appropriate.

    RESULT
        This function will return the number of tasks signaled.

    BUGS

    SEE ALSO
        ResetDinLinkFlags


din.library/ResetDinLinkFlags            din.library/ResetDinLinkFlags

    NAME
    ResetDinLinkFlags  --  Clear all the notify flags for a DinLink.

    SYNOPSIS
    ResetDinLinkFlags(DinLink)
                A0

    struct DinLink *DinLink;

    FUNCTION
    Clears all notify flags in the DinLink Flags field.

    Use this function after you have examined the DinLink flags.
    If you forget to do this you will not be able to distinguish
    between different notify signals.

    Note! The only flag not cleared is the LNK_KILLED flag.

    INPUTS
        DinLink = a pointer to a DinLink structure

    RESULT
        None

    BUGS

    SEE ALSO
        NotifyDinLinks


din.library/MakeDinObject            din.library/MakeDinObject

    NAME
    MakeDinObject  --  Make a DinObject.

    SYNOPSIS
    DinObject = MakeDinObject(Name,Type,Flags,PhysicalObject,Size)
    D0               A0    D0    D1    A1       D2

    struct DinObject *DinObject;
    char *Name;
    UWORD Type;
    ULONG Flags;
    APTR PhysicalObject;
    ULONG Size;

    FUNCTION
        Make a DinObject available to all possible linkers.

    There are three possible actions for this function:
    - There is already an object with this name.
      Return NULL, this is an error.
    - There is no one waiting for this object to arrive.
      The object is created.
    - There are already links to this object.
      Create the object and send a LNK_NEW signal to all linked tasks.

    'Name' is copied to an internal buffer, so you don't need to worry
    about this one.

    It is perfectly legal to make an object and exit. This is called a
    resident object. Because it would be nice if you could remove this
    object later on, you should Propagate the ownership of the object
    to nobody before you exit (with PropagateDinObject). This is
    because only the owner can remove a DinObject.

    What this function does:
    - Allocate the object structure.
    - Initialize the two semaphores.
    - Initialize the DinLink list.
    - Set the owner pointer to the current task.
    - Set the pointer to the Physical object. (Note that you don't
      have to initialize the physical object before you create the
      DinObject. You can do this later. You should, however, do this
      before you enable the DinObject.
    - The DinObject is disabled by default. Enable it with EnableDinObject.
    - Link the DinObject in the library list.
    - If the DinObject had some links, notify signals are send (LNK_NEW).

    A DinObject corresponds directly with a physical object. The physical
    objects that are supported at this moment are:
    - OBJECTDATA :
        Binary data.
        struct ObjectData
            {
              ULONG Size;
              APTR Data;
            }
        Data must be allocated with 'AllocMem (Size,MEMF...)'.
        If you use this object type you are responsible for your own
        physical object interpretation. The din library only knows how
        to deallocate your 'Data'.
    - OBJECTTEXT :
        Text data.
        struct ObjectText
            {
              ULONG Lines;
              struct ObjectLine *FirstLine;
            }
        struct ObjectLine
            {
              struct ObjectLine *Next;
              char FirstByte;
            }
        Lines is the number of lines in the text.
        FirstLine points to the first line of text (pffh, how difficult :-)
    - OBJECTIMAGE :
        Image data.
        struct ImageData
            {
              struct RastPort *rp;
              struct Rectangle Rect;
            }
        RastPort is ofcourse the RastPort for the drawing.
        Rect is a rectangle describing the image in this RastPort. If all
        values in the rectangle are ~0, the image corresponds with the
        complete RastPort.
    - OBJECTACK :
        Acknowledgement object.
        There is no structure for this object.
        It is simply a way to let someone know that you are here.
        PhysicalObject is NULL and Size is 0.

    INPUTS
        Name = pointer to a unique name. If the name already exists, you will
          get an error.
        Type = the physical object type. Supported physical objects at this moment
          are:
            - OBJECTDATA : Binary data, for own interpretation.
            - OBJECTTEXT : Text data.
            - OBJECTIMAGE : RastPort.
            - OBJECTACK : Acknowledgement.
        Flags = OB_READONLY if only the owner may write on this object.
        PhysicalObject = pointer to the physical object. You may initialize this
          later.
        Size = size of the physical object structure.

    RESULT
        Pointer to the freshly created DinObject or NULL if no success.

    BUGS

    SEE ALSO
    RemoveDinObject


din.library/EnableDinObject            din.library/EnableDinObject

    NAME
    EnableDinObject  --  Make a DinObject available for use.

    SYNOPSIS
    Success = EnableDinObject(DinObject)
    D0                 A0

    BOOL Success;
    struct DinObject *DinObject;

    FUNCTION
        Make a DinObject available for use.

    Only the owner of the DinObject can enable it.
    This function sends a LNK_ENABLE signal to all linked tasks.

    INPUTS
        DinObject = pointer to a DinObject.

    RESULT
        FALSE if you are not allowed to enable this DinObject.

    BUGS

    SEE ALSO
    DisableDinObject


din.library/DisableDinObject            din.library/DisableDinObject

    NAME
    DisableDinObject  --  Make a DinObject unavailable for use.

    SYNOPSIS
    Success = DisableDinObject(DinObject)
    D0                  A0

    BOOL Success;
    struct DinObject *DinObject;

    FUNCTION
        Make a DinObject unavailable for use.

    Only the owner of the DinObject can disable it.
    This function sends a LNK_DISABLE signal to all linked tasks.
    When someone is still writing or reading on the physical object for
    this DinObject, this function will block.

    INPUTS
        DinObject = pointer to a DinObject.

    RESULT
        FALSE if you are not allowed to disable this DinObject.

    BUGS

    SEE ALSO
    EnableDinObject


din.library/PropagateDinObject            din.library/PropagateDinObject

    NAME
    PropagateDinObject  --  Change the ownership of a DinObject.

    SYNOPSIS
    Success = PropagateDinObject(DinObject,Task)
    D0                A0    A1

    BOOL Success;
    struct DinObject *DinObject;
    struct Task *Task;

    FUNCTION
        Change the ownership of a DinObject.

    Only the owner of the DinObject can change the ownership.
    If task == NULL no one will be the owner.

    The owner of a DinObject can:
    - Remove, Disable and Enable it.
    - Change the ownership.
    - Write on a READ ONLY physical object.

    INPUTS
        DinObject = pointer to a DinObject.
        Task = pointer to a task or NULL for no one.

    RESULT
        FALSE if you are not the owner of this DinObject.

    BUGS
    Does not check for ownership.

    SEE ALSO


din.library/RemoveDinObject            din.library/RemoveDinObject

    NAME
    RemoveDinObject  --  Remove a DinObject.

    SYNOPSIS
    Success = RemoveDinObject(DinObject)
    D0                 A0

    BOOL Success;
    struct DinObject *DinObject;

    FUNCTION
        Remove a DinObject.

    Only the owner of the DinObject can remove a DinObject.

    This function will send a LNK_KILLED signal to all tasks still linked
    to this DinObject. Note that this function will NOT remove the links
    attached to this DinObject. The linkers themselves are responsible for
    removing their DinLinks after they received a LNK_KILLED signal.

    This function will NOT deallocate the physical object. You are
    responsible for that. Note that if you want to deallocate the
    physical object before you remove the DinObject, you MUST disable
    the DinObject first.

    INPUTS
        DinObject = pointer to a DinObject. You can safely pass a NULL pointer.

    RESULT
        FALSE if you are not the owner of this DinObject.

    BUGS

    SEE ALSO
        MakeDinObject


din.library/LockDinObject            din.library/LockDinObject

    NAME
    LockDinObject  --  Lock the DinObject structure.

    SYNOPSIS
    Success = LockDinObject(DinObject)
    D0               A0

    BOOL Success;
    struct DinObject *DinObject;

    FUNCTION
    Lock The DinObject structure.

    Use this function if you want to look at the fields in the DinObject
    structure.
    Always pair a LockDinObject with an UnlockDinObject.

    Locks can be nested.

    INPUTS
        DinObject = pointer to a DinObject.

    RESULT
        FALSE if the DinObject is not ready (if it is a Dummy object).

    BUGS
    Avoid these functions if possible. Use InfoDinObject instead.

    SEE ALSO
        UnlockDinObject, InfoDinObject


din.library/UnlockDinObject            din.library/UnlockDinObject

    NAME
    UnlockDinObject  --  Lock the DinObject structure.

    SYNOPSIS
    UnlockDinObject(DinObject)
               A0

    BOOL Success;
    struct DinObject *DinObject;

    FUNCTION
    Unlock The DinObject structure.

    Only use this function if you have Locked the DinObject first.
    Always pair a LockDinObject with an UnlockDinObject.

    Locks can be nested.

    INPUTS
        DinObject = pointer to a DinObject.

    RESULT
    None.

    BUGS
    Avoid these functions if possible. Use InfoDinObject instead.

    SEE ALSO
        LockDinObject, InfoDinObject


din.library/FindDinObject            din.library/FindDinObject

    NAME
    FindDinObject  --  Search a named DinObject.

    SYNOPSIS
    DinObject = FindDinObject(Name)
    D0               A0

    struct DinObject *DinObject;
    char *Name;

    FUNCTION
    Search a DinObject in the DinObject list.

    This function arbitrates for access to the DinObject list.

    INPUTS
        Name = pointer to a NULL-terminated name.

    RESULT
    Pointer to a DinObject or NULL if not found.

    BUGS

    SEE ALSO


din.library/MakeDinLink                din.library/MakeDinLink

    NAME
    MakeDinLink  --  Create a link to a DinObject.

    SYNOPSIS
    DinLink = MakeDinLink(DinObject,[Name])
    D0              A0      A1

    struct DinLink *DinLink;
    struct DinObject *DinObject;
    char *Name;

    FUNCTION
    Create a DinLink to a DinObject.

    There are three scenarios:
    - The DinObject exists.
      The Link is immediate, no LNK_NEW will be send.
    - The DinObject does not exist.
      This Function will create a dummy DinObject with the name you
      specified. The LNK_WAITING4OB flag is set. When the object
      is created you will get a LNK_NEW signal.
    - The DinObject does exist as a dummy.
      The LNK_WAITING4OB flag is set. When the object is created
      you will get a LNK_NEW signal.

    This means that a link will almost always succeed (except when
    there is not enough memory) even if the object does not exist.
    If you only want to link to an existing DinObject you should use
    the following code (or something equivalent):

      link = MakeDinLink (0,"Object");
      if (!link)
        {
          printf ("Not enough memory\n");
          exit (1);
        }
      if (link->Flags & LNK_WAITING4OB)
        {
          RemoveDinLink (link);
          printf ("Object does not exist\n");
          exit (1);
        }

    Note that you MUST check the LNK_WAITING4OB flag and handle
    this situation correctly.
    Also note that your program must be able to respond to all
    available signals correctly:
    - LNK_CHANGE :
      The physical object has changed.
    - LNK_NEW :
      The object has just been made.
    - LNK_DISABLE :
      The object has been disabled.
    - LNK_ENABLE :
      The object has been enabled.
    - LNK_KILLED :
      The object has been killed. You should remove your DinLink as
      soon as possible.

    This function allocates a Signal.

    INPUTS
        DinObject = pointer to a DinObject. if NULL Name is used.
        Name = pointer to a NULL-terminated name.

    RESULT
    Pointer to a DinLink or NULL if an error occured.

    BUGS
    Future plans incorporate a system to share a signal for several links.

    SEE ALSO
        RemoveDinLink


din.library/RemoveDinLink            din.library/RemoveDinLink

    NAME
    RemoveDinLink  --  Remove a link to a DinObject.

    SYNOPSIS
    RemoveDinLink(DinLink)
             A0

    struct DinLink *DinLink;

    FUNCTION
        Remove a link to a DinObject.

    If the link is the last link in a dummy object, this dummy object
    is removed.
    If the DinObject is waiting to be deleted and your link is the
    last to be removed, the dummy object is removed.

    INPUTS
        DinLink = pointer to a DinLink. It is safe to call this routine with
          a NULL pointer.

    RESULT
    None.

    BUGS

    SEE ALSO
        MakeDinLink


din.library/ReadLockDinObject            din.library/ReadLockDinObject

    NAME
    ReadLockDinObject  --  Lock a DinObject for reading.

    SYNOPSIS
    Success = ReadLockDinObject(DinObject)
    D0                A0

    BOOL Success;
    struct DinObject *DinObject;

    FUNCTION
    Lock the physical object of a DinObject for reading.

    Note that there can be more readers at the same time, but only
    one writer.

    INPUTS
        DinObject = pointer to a DinObject.

    RESULT
    FALSE if object is disabled.

    BUGS

    SEE ALSO
    ReadUnlockDinObject, WriteLockDinObject, WriteUnlockDinObject


din.library/ReadUnlockDinObject            din.library/ReadUnlockDinObject

    NAME
    ReadUnlockDinObject  --  Unlock a DinObject for reading.

    SYNOPSIS
    ReadUnlockDinObject(DinObject)
                A0

    struct DinObject *DinObject;

    FUNCTION
    Unlock the physical object of a DinObject for reading.

    Note that there can be more readers at the same time, but only
    one writer.

    INPUTS
        DinObject = pointer to a DinObject.

    RESULT
    None.

    BUGS

    SEE ALSO
    ReadLockDinObject, WriteLockDinObject, WriteUnlockDinObject


din.library/WriteLockDinObject            din.library/WriteLockDinObject

    NAME
    WriteLockDinObject  --  Lock a DinObject for writing.

    SYNOPSIS
    Success = WriteLockDinObject(DinObject)
    D0                A0

    BOOL Success;
    struct DinObject *DinObject;

    FUNCTION
    Lock the physical object of a DinObject for writing.

    Note that there can be more readers at the same time, but only
    one writer.

    INPUTS
        DinObject = pointer to a DinObject.

    RESULT
    FALSE if object is disabled.

    BUGS

    SEE ALSO
    ReadLockDinObject, ReadUnlockDinObject, WriteUnlockDinObject


din.library/WriteUnlockDinObject        din.library/WriteUnlockDinObject

    NAME
    WriteUnlockDinObject  --  Unlock a DinObject for writing.

    SYNOPSIS
    WriteUnlockDinObject(DinObject)
                A0

    struct DinObject *DinObject;

    FUNCTION
    Unlock the physical object of a DinObject for writing.

    Note that there can be more readers at the same time, but only
    one writer.

    INPUTS
        DinObject = pointer to a DinObject.

    RESULT
    None.

    BUGS

    SEE ALSO
    ReadUnlockDinObject, ReadLockDinObject, WriteLockDinObject


din.library/LockDinBase                din.library/LockDinBase

    NAME
    LockDinBase  --  Lock DinBase for reading.

    SYNOPSIS
    LockDinBase()

    FUNCTION
    Lock DinBase for reading.

    INPUTS
    None.

    RESULT
    None.

    BUGS

    SEE ALSO
    UnlockDinBase


din.library/UnlockDinBase            din.library/UnlockDinBase

    NAME
    UnlockDinBase  --  Unlock DinBase for reading.

    SYNOPSIS
    UnlockDinBase()

    FUNCTION
    Unlock DinBase for reading.

    INPUTS
    None.

    RESULT
    None.

    BUGS

    SEE ALSO
    LockDinBase


din.library/InfoDinObject            din.library/InfoDinObject

    NAME
    InfoDinObject  --  Copies readable fields from a DinObject.

    SYNOPSIS
    InfoDinObject = InfoDinObject(DinObject)
    D0                  A0

    struct InfoDinObject *InfoDinObject;
    struct DinObject *DinObject;

    FUNCTION
    This function copies some readable fields from the DinObject to
    a InfoDinObject structure (see din.h for details). It is the
    recommended way to get some information from a DinObject.

    This function allocates a InfoDinObject for you and returns the
    pointer to it. Use FreeInfoDinObject to free this block.

    INPUTS
    DinObject = pointer to a DinObject.

    RESULT
    Pointer to a InfoDinObject structure or NULL if not enough memory.

    BUGS

    SEE ALSO
    FreeInfoDinObject


din.library/FreeInfoDinObject            din.library/FreeInfoDinObject

    NAME
    FreeInfoDinObject  --  Frees the InfoDinObject created by InfoDinObject.

    SYNOPSIS
    FreeInfoDinObject(InfoDinObject)
                A0

    struct InfoDinObject *InfoDinObject;

    FUNCTION
    Use this function to free the block obtained by InfoDinObject.

    INPUTS
    InfoDinObject = pointer to a InfoDinObject (can be NULL).

    RESULT
    None.

    BUGS

    SEE ALSO
    InfoDinObject